<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Memory Objects - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/zend.memory.memory-objects.html">Inglês (English)</a></li>
    <li><a href="../pt-br/zend.memory.memory-objects.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.memory.memory-manager.html">Memory Manager</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.memory.html">Zend_Memory</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.mime.html">Zend_Mime</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="zend.memory.memory-objects" class="section"><div class="info"><h1 class="title">Memory Objects</h1></div>
    

    <div class="section" id="zend.memory.memory-objects.movable"><div class="info"><h1 class="title">Movable</h1></div>
        

        <p class="para">
            Create movable memory objects using the  <span class="methodname">create([$data])</span>
            method of the memory manager:
        </p>

        <pre class="programlisting brush: php">
$memObject = $memoryManager-&gt;create($data);
</pre>


        <p class="para">
            &quot;Movable&quot; means that such objects may be swapped and unloaded from
            memory and then loaded when application code accesses the object.
        </p>
    </div>

    <div class="section" id="zend.memory.memory-objects.locked"><div class="info"><h1 class="title">Locked</h1></div>
        

        <p class="para">
            Create locked memory objects using the  <span class="methodname">createLocked([$data])</span>
            method of the memory manager:
        </p>

        <pre class="programlisting brush: php">
$memObject = $memoryManager-&gt;createLocked($data);
</pre>


        <p class="para">
            &quot;Locked&quot; means that such objects are never swapped and unloaded
            from memory.
        </p>

        <p class="para">
            Locked objects provides the same interface as movable objects
            (<span class="classname">Zend_Memory_Container_Interface</span>).
            So locked object can be used in any place instead of movable objects.
        </p>

        <p class="para">
            It&#039;s useful if an application or developer can decide, that some
            objects should never be swapped, based on performance considerations.
        </p>

        <p class="para">
            Access to locked objects is faster, because the memory manager doesn&#039;t
            need to track changes for these objects.
        </p>

        <p class="para">
            The locked objects class (<span class="classname">Zend_Memory_Container_Locked</span>)
            guarantees virtually the same performance as working with a string
            variable. The overhead is a single dereference to get the class property.
        </p>
    </div>

    <div class="section" id="zend.memory.memory-objects.value"><div class="info"><h1 class="title">Memory container &#039;value&#039; property</h1></div>
        

        <p class="para">
            Use the memory container (movable or locked) &#039;<span class="property">value</span>&#039;
            property to operate with memory object data:
        </p>

        <pre class="programlisting brush: php">
$memObject = $memoryManager-&gt;create($data);

echo $memObject-&gt;value;

$memObject-&gt;value = $newValue;

$memObject-&gt;value[$index] = &#039;_&#039;;

echo ord($memObject-&gt;value[$index1]);

$memObject-&gt;value = substr($memObject-&gt;value, $start, $length);
</pre>


        <p class="para">
            An alternative way to access memory object data is to use the <a href="zend.memory.memory-objects.html#zend.memory.memory-objects.api.getRef" class="link"> <span class="methodname">getRef()</span></a>
            method. This method <em class="emphasis">must</em> be used for <acronym class="acronym">PHP</acronym>
            versions before 5.2. It also may have to be used in some other
            cases for performance reasons.
        </p>
    </div>

    <div class="section" id="zend.memory.memory-objects.api"><div class="info"><h1 class="title">Memory container interface</h1></div>
        

        <p class="para">
            Memory container provides the following methods:
        </p>

        <div class="section" id="zend.memory.memory-objects.api.getRef"><div class="info"><h1 class="title">getRef() method</h1></div>
            

            <pre class="programlisting brush: php">
public function &amp;getRef();
</pre>


            <p class="para">
                The  <span class="methodname">getRef()</span> method returns reference to the object value.
            </p>

            <p class="para">
                Movable objects are loaded from the cache at this moment if the
                object is not already in memory. If the object is loaded from
                the cache, this might cause swapping of other objects if the
                memory limit would be exceeded by having all the managed
                objects in memory.
            </p>

            <p class="para">
                The  <span class="methodname">getRef()</span> method <em class="emphasis">must</em> be
                used to access memory object data for <acronym class="acronym">PHP</acronym> versions before 5.2.
            </p>

            <p class="para">
                Tracking changes to data needs additional resources.
                The  <span class="methodname">getRef()</span> method returns reference to string,
                which is changed directly by user application.
                So, it&#039;s a good idea to use the  <span class="methodname">getRef()</span> method
                for value data processing:
            </p>

            <pre class="programlisting brush: php">
$memObject = $memoryManager-&gt;create($data);

$value = &amp;$memObject-&gt;getRef();

for ($count = 0; $count &lt; strlen($value); $count++) {
    $char = $value[$count];
    ...
}
</pre>

        </div>

        <div class="section" id="zend.memory.memory-objects.api.touch"><div class="info"><h1 class="title">touch() method</h1></div>
            

            <pre class="programlisting brush: php">
public function touch();
</pre>


            <p class="para">
                The  <span class="methodname">touch()</span> method should be used in common with
                 <span class="methodname">getRef()</span>. It signals that object value has been changed:
            </p>

            <pre class="programlisting brush: php">
$memObject = $memoryManager-&gt;create($data);
...

$value = &amp;$memObject-&gt;getRef();

for ($count = 0; $count &lt; strlen($value); $count++) {
    ...
    if ($condition) {
        $value[$count] = $char;
    }
    ...
}

$memObject-&gt;touch();
</pre>

        </div>

        <div class="section" id="zend.memory.memory-objects.api.lock"><div class="info"><h1 class="title">lock() method</h1></div>
            

            <pre class="programlisting brush: php">
public function lock();
</pre>


            <p class="para">
                The  <span class="methodname">lock()</span> methods locks object in memory.
                It should be used to prevent swapping of some objects you choose.
                Normally, this is not necessary, because the memory manager uses
                an intelligent algorithm to choose candidates for swapping.
                But if you exactly know, that at this part of code some
                objects should not be swapped, you may lock them.
            </p>

            <p class="para">
                Locking objects in memory also guarantees that reference
                returned by the  <span class="methodname">getRef()</span> method is valid until you
                unlock the object:
            </p>

            <pre class="programlisting brush: php">
$memObject1 = $memoryManager-&gt;create($data1);
$memObject2 = $memoryManager-&gt;create($data2);
...

$memObject1-&gt;lock();
$memObject2-&gt;lock();

$value1 = &amp;$memObject1-&gt;getRef();
$value2 = &amp;$memObject2-&gt;getRef();

for ($count = 0; $count &lt; strlen($value2); $count++) {
    $value1 .= $value2[$count];
}

$memObject1-&gt;touch();
$memObject1-&gt;unlock();
$memObject2-&gt;unlock();
</pre>

        </div>

        <div class="section" id="zend.memory.memory-objects.api.unlock"><div class="info"><h1 class="title">unlock() method</h1></div>
            

            <pre class="programlisting brush: php">
public function unlock();
</pre>


            <p class="para">
                 <span class="methodname">unlock()</span> method unlocks object when it&#039;s no longer
                necessary to be locked. See the example above.
            </p>
        </div>

        <div class="section" id="zend.memory.memory-objects.api.isLocked"><div class="info"><h1 class="title">isLocked() method</h1></div>
            

            <pre class="programlisting brush: php">
public function isLocked();
</pre>


            <p class="para">
                The  <span class="methodname">isLocked()</span> method can be used to check if
                object is locked. It returns <b><tt>TRUE</tt></b> if the object
                is locked, or <b><tt>FALSE</tt></b> if it is not locked.
                This is always <b><tt>TRUE</tt></b> for &quot;locked&quot; objects,
                and may be either <b><tt>TRUE</tt></b> or <b><tt>FALSE</tt></b>
                for &quot;movable&quot; objects.
            </p>
        </div>
    </div>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.memory.memory-manager.html">Memory Manager</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.memory.html">Zend_Memory</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.mime.html">Zend_Mime</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="reference.html">Zend Framework Reference</a></li>
  <li class="header up"><a href="zend.memory.html">Zend_Memory</a></li>
  <li><a href="zend.memory.overview.html">Overview</a></li>
  <li><a href="zend.memory.memory-manager.html">Memory Manager</a></li>
  <li class="active"><a href="zend.memory.memory-objects.html">Memory Objects</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>